.so ../bk-macros
.TH "bk set" "\*[BKVER]" %E% "\*(BC" "\*(UM"
.SH NAME
bk set \- set operations
.SH SYNOPSIS
.B bk set
.[B] \-adeklnosSx
.[OPTreq] \-r rev
.[OPTopt] \-t type
.[ARG] file
.SH DESCRIPTION
The 
.B bk set
command performs set operations on a \*(BK file.  This command provides 
the following set operations: union, intersection, difference and symmetric
difference.  It also provides the member function (is this element a member
of the set?) as well as the list function (list all sets which contain this
member).
.LP
If the file is not specified, it defaults to the ChangeSet file.
.SH OUTPUT OPTIONS
The default output is a list of revisions, one per line.  The output
may be restricted to only tagged revisions, and may be forced into
revision, tag, or key format.  Note that only the ChangeSet file may
have tags, which means that combining tag output format with a regular
file has unexpected results.
.TP 
.B \-k
list all answers as keys, not as tags or revisions.
.tp
.B \-n
prefix each output line with the filename, i.e., ChangeSet|1.3, so that
the output may be fed to other programs, such as
.BR "bk log" .
.tp
.B \-t
list all answers as tags where possible, else revisions.
.tp
.B \-tt
list only those answers which are tagged and list those as the tag
not the revision.
.tp
.B \-tr
list only those answers which are tagged but list those as revisions.
.tp
.B \-tk
list only those answers which are tagged but list those as keys.
.SH SPECIFYING SETS
If a revision is specified for a set argument, the set is the set of
deltas which make up that revision.  For example, in a simple history
without branches, revision 1.5 implies the set {1.1, 1.2, 1.3, 1.4, 1.5}.
A revision may be specified as a revision, as a symbolic tag,
or as a \*(BK key.  It may also be specified as a \*(lq\-\*(rq, for the second
set only, in which case it expects a list of revisions (or keys) on
stdin, one per line.
.SH SET OPERATIONS
.SS UNION (\*[<]setA\*[>] | \*[<]setB\*[>])
.B bk set
.[ARG] "output opts"
.B \-o
.ARG setA
.ARG setB
.[ARG] file
.LP
The union operation, familiar to programmers as a \*(lqbitwise or\*(rq,
lists all members which occur in either set.
.SS INTERSECTION (\*[<]setA\*[>] & \*[<]setB\*[>])
.B bk set
.[ARG] "output opts"
.B \-a
.ARG setA
.ARG setB
.[ARG] file
.LP
The intersection operator, familiar to programmers as a \*(lqbitwise and\*(rq,
lists all members which occur in both sets.
.SS DIFFERENCE (~\*[<]setA\*[>] & \*[<]setB\*[>])
.B bk set
.[ARG] "output opts"
.B \-d
.ARG setA
.ARG setB
.[ARG] file
.LP
The difference operator lists all members in
.I setB
which are not in
.IR setA .
This is the most useful of the set operations, see the examples below.
.SS SYMMETRIC DIFFERENCE (\*[<]setA\*[>] ^ \*[<]setB\*[>])
.B bk set
.[ARG] "output opts"
.B \-x
.ARG setA
.ARG setB
.[ARG] file
.LP
The symmetric difference operator, familiar to programmers as an
\*(lqexclusive or\*(rq,
lists all members which occur in only one of the two sets.
.SS ELEMENT
.B bk set
.[ARG] "output opts"
.B \-e
.OPTreq \-r rev
.ARG setA
.[ARG] file
.LP
The element operator treats the specified revision as a single element,
not as an implied set, and lists the element if it is in the set.
.SS LIST
.B bk set \-l
.OPTreq \-r rev
.[ARG] file
.LP
The list operator treats the specified revision as a single element,
not as an implied set, and lists all sets (as revisions) which contain
the element as part of their set.
It is typically used to see if a bug
fix is in a particular release.  If the changeset has been excluded from
a later changeset, the later changeset and its descendants will not be
listed.
.SS SET
.B bk set \-s
.OPTreq \-r rev
.[ARG] file
.LP
The set operator treats the specified revision as a set,
and lists all elements of that set.
.SH NESTED
The set command will look at the product changeset file by default.
.TP
.B \-S
perform the set operation on the current component.
.SH EXAMPLES
A good use of this command is the generation of release notes.  To do
so, pick the starting and ending points and do this:
.DS
$ bk set -d -rbk-2.0 -rbk-2.0.1 | bk changes -
ChangeSet@1.1425.5.19, 2001-10-12 15:18:06, lm@work
  utils.c:
    Remove debugging.
    Sleep 50 milliseconds when waiting for the lock.

ChangeSet@1.1425.5.20, 2001-10-15 15:57:42, lm@disks
  A weekend's worth of testing of locking over NFS
  turned into this cset.

ChangeSet@1.1425.5.21, 2001-10-16 08:35:26, lm@disks
  The cset lock was too fine grained.
  This is a short term fix,
  the longer term fix is the per file locking
  Andrew is working on.
  TAG: bk-2.0.1
.DE
To see the tagged releases which contain bk-2.0.3:
.DS
$ bk set -l -tt -rbk-2.0.3 
bk-2.0.3
bk-2.0.4
bk-2.0.4b
bk-2.1.2
bk-2.1.3
bk-3par_merge
bk-3par_merge2
.DE
.SH SEE ALSO
.SA changes
.SA log
.SH CATEGORY
.B Utility
